cc-pocket · mobile ui 2.0 · session · worktrees · v1

Worktrees v1

A repository can be checked out several times at once — one directory per branch, one agent per directory. Today the phone cannot tell which session runs where, and cannot make or clean a checkout. This surface answers both: it lists the worktrees, says which one has a live session, and adds or removes them behind the same guards as the Git panel. Entered from the Git panel header or from the directory list. Owner-only.

390 × 844
dark · 1:1
3 screens
11 frames
4 verbs
allow-list

A worktree is a branch and a path. Both are shown, both in mono, in that order. Every other fact on the card is a chip, so the card has exactly two lines you read and one line you scan.

The chips reuse the Git panel's colours. Amber is a working change, green is clean, grey is unknown, terracotta is ours — a live session. Nothing new has to be learnt to read this list.

Creating is safe, removing is not. New worktree sits at the top in accent and acts in one tap. Remove is one level down in the overflow, ends in an ellipsis, and raises the same destructive sheet shape as revert file.

A running session outranks the request. Removal is blocked, not warned about, while an agent holds the directory — the phone will not stop someone's work to make room for a delete.

A

Screen A · Worktree list

Repo header, the New row, one card per checkout.
A1 · canonical · three worktrees

Repo name is the title and the root path is its subtitle, middle-truncated from the left so the repo folder never leaves the screen. The card with a live session carries a faint terracotta border as well as its chip, which is what makes the answer to “where is my agent running” a glance rather than a read.

A2 · single-worktree repo

Most repos live here, and for them the screen has one job: explain the feature in one sentence and leave. No illustration, no empty state — the main worktree is real content, so the list is not empty, it is short.

A3 · dirty status unknown

Reading status in every checkout costs a scan we may not have run yet. Grey says so plainly and blocks nothing: the overflow, Open session and Remove all still work, and the footnote states when the answer arrives rather than leaving a spinner turning.

A4 · loading

The skeleton keeps the card geometry — glyph, branch, path, two chips — so nothing shifts when the list resolves. Repo name and root are known from the session already, and New worktree stays live because it does not depend on the scan.

A5 · overflow · linked worktree

Two useful verbs and one dangerous one, in that order, with the danger last and in danger ink. Nothing here acts immediately; Remove… leads to C.

A6 · overflow · main worktree

The primary worktree's menu simply does not contain Remove — the item is absent rather than disabled, because a disabled row invites a tap and then explains a rule that will never change.

B

Screen B · New worktree

Bottom sheet. One choice, one name, one computed path.
B1 · existing branch

The list is ordered by last commit, searchable, and honest about the constraint git enforces: a branch already checked out somewhere is dimmed and names the worktree holding it. That turns the one confusing failure of worktree add into a fact you can read before you tap.

B2 · new branch

Location is the same read-only row in both segments and updates as you type, with slashes flattened to dashes so the directory name is never a surprise. The caption states the one policy the preview cannot show: it is created next to the repository, never inside it.

C1 · remove · dirty

Screen C, step two of the removal. Same shape as the Git panel's discard sheet: branch in the title, path underneath, then the loss itemised in mono. The closing sentence separates what dies from what survives — the directory goes, the branch stays.

C2 · remove · session running

A block, not a warning. Grey rather than red because nothing is wrong, the badge turns into an i, the panel names the session and its runtime, and Remove is inert until that session stops.

D · component · directory row

One row variant for the existing directory picker: a mono ⎇ part of cc-pocket caption under the folder name. It stops someone opening a linked checkout believing it is a separate project, and it is the second entrance to Screen A.

E

Allow-list contract

Four verbs, added to the nine in the Git panel.
VerbEntryGuardNever
{{ v.verb }} {{ v.entry }} {{ v.guard }} {{ v.never }}

Where this composes. The Git panel header gains a worktree line when the repo has more than one checkout, and its branch sheet keeps working per worktree. Session cards elsewhere in the app can now name their checkout, which is the point of building this.

Prune is not drawn. A worktree whose directory was deleted from the computer shows as a stale entry git still tracks; the repair verb is worktree prune and it needs its own state on Screen A. Open.

Also open. The base ref for a new branch is fixed to the default branch here and may need to be selectable. Bare-repo layouts are out of scope. Nothing on this surface reaches a submodule.